.de IQ
.  br
.  ns
.  IP "\\$1"
..
.TH ovs\-vlan\-test 1 "2.5.0" "Open vSwitch" "Open vSwitch Manual"
.
.SH NAME
\fBovs\-vlan\-test\fR \- check Linux drivers for problems with vlan traffic
.
.SH SYNOPSIS
\fBovs\-vlan\-test\fR [\fB\-s\fR | \fB\-\-server\fR] \fIcontrol_ip\fR \fIvlan_ip\fR
.IP "Common options:"
[\fB\-h\fR | \fB\-\-help\fR]
[\fB\-V\fR | \fB\-\-version\fR]

.
.SH DESCRIPTION
The \fBovs\-vlan\-test\fR utility has some limitations, for example, it does
not use TCP in its tests. Also it does not take into account MTU to detect
potential edge cases. To overcome those limitations a new tool was
developed \- \fBovs\-test\fR. \fBovs\-test\fR is currently supported only
on Debian so, if possible try to use that on instead of \fBovs\-vlan\-test\fR.
.PP
The \fBovs\-vlan\-test\fR program may be used to check for problems sending
802.1Q traffic which may occur when running Open vSwitch. These problems can
occur when Open vSwitch is used to send 802.1Q traffic through physical
interfaces running certain drivers of certain Linux kernel versions. To run a
test, configure Open vSwitch to tag traffic originating from \fIvlan_ip\fR and
forward it out the target interface. Then run the \fBovs\-vlan\-test\fR in
client mode connecting to an \fBovs\-vlan\-test\fR server.
\fBovs\-vlan\-test\fR will display "OK" if it did not detect problems.
.PP
Some examples of the types of problems that may be encountered are:
.IP \(bu
When NICs use VLAN stripping on receive they must pass a pointer to a
\fBvlan_group\fR when reporting the stripped tag to the networking
core.  If no \fBvlan_group\fR is in use then some drivers just drop
the extracted tag.  Drivers are supposed to only enable stripping if a
\fBvlan_group\fR is registered but not all of them do that.
.
.IP \(bu
On receive, some drivers handle priority tagged packets specially and
don't pass the tag onto the network stack at all, so Open vSwitch
never has a chance to see it.
.
.IP \(bu
Some drivers size their receive buffers based on whether a
\fBvlan_group\fR is enabled, meaning that a maximum size packet with a
VLAN tag will not fit if no \fBvlan_group\fR is configured.
.
.IP \(bu
On transmit, some drivers expect that VLAN acceleration will be used
if it is available, which can only be done if a \fBvlan_group\fR is
configured.  In these cases, the driver may fail to parse the packet
and correctly setup checksum offloading or TSO.
.
.SS "Client Mode"
An \fBovs\-vlan\-test\fR client may be run on a host to check for VLAN
connectivity problems.  The client must be able to establish HTTP connections
with an \fBovs\-vlan\-test\fR server located at the specified \fIcontrol_ip\fR
address.  UDP traffic sourced at \fIvlan_ip\fR should be tagged and directed out
the interface whose connectivity is being tested.
.
.SS "Server Mode"
To conduct tests, an \fBovs\-vlan\-test\fR server must be running on a host
known not to have VLAN connectivity problems.  The server must have a
\fIcontrol_ip\fR on a non\-VLAN network which clients can establish
connectivity with.  It must also have a \fIvlan_ip\fR address on a VLAN network
which clients will use to test their VLAN connectivity.  Multiple clients may
test against a single \fBovs\-vlan\-test\fR server concurrently.
.
.SH OPTIONS
.
.IP "\fB\-s\fR"
.IQ "\fB\-\-server\fR"
Run in server mode.
.
.de IQ
.  br
.  ns
.  IP "\\$1"
..
.IP "\fB\-h\fR"
.IQ "\fB\-\-help\fR"
Prints a brief help message to the console.
.
.IP "\fB\-V\fR"
.IQ "\fB\-\-version\fR"
Prints version information to the console.
.SH EXAMPLES
Display the Linux kernel version and driver of \fBeth1\fR.
.IP
.B uname \-r
.IP
.B ethtool \-i eth1
.
.PP
Set up a bridge which forwards traffic originating from \fB1.2.3.4\fR out
\fBeth1\fR with VLAN tag 10.
.IP
.B ovs\-vsctl \-\- add\-br vlan\-br \(rs
.IP
.B \-\- add\-port vlan\-br eth1 \(rs
.IP
.B \-\- add\-port vlan\-br vlan\-br\-tag tag=10 \(rs
.IP
.B \-\- set Interface vlan\-br\-tag type=internal
.IP
.B ifconfig vlan\-br\-tag up 1.2.3.4
.
.PP
Run an \fBovs\-vlan\-test\fR server listening for client control traffic on
172.16.0.142 port 8080 and VLAN traffic on the default port of 1.2.3.3.
.IP
.B ovs\-vlan\-test \-s 172.16.0.142:8080 1.2.3.3
.
.PP
Run an \fBovs\-vlan\-test\fR client with a control server located at
172.16.0.142 port 8080 and a local VLAN ip of 1.2.3.4.
.IP
.B ovs\-vlan\-test 172.16.0.142:8080 1.2.3.4
.
.SH SEE ALSO
.
.BR ovs\-vswitchd (8),
.BR ovs\-ofctl (8),
.BR ovs\-vsctl (8),
.BR ovs\-test (8),
.BR ethtool (8),
.BR uname (1)
